home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 526-550 / disk_535 / keymacro / keymacro.doc < prev    next >
Text File  |  1992-05-06  |  14KB  |  296 lines
  1. ======================================================================
  2. =========================== KeyMacro v1.12 ===========================
  3. ================== * A macro key handler utility * ===================
  4. ======================================================================
  5.  
  6. ============================= IMPORTANT ==============================
  7. ======================================================================
  8. The  current release of KeyMacro requires arp.library and Null-Handler
  9. to  be  present  in  your system.  Put the library into LIBS:  and the
  10. handlers into L:.  Then add the following lines to DEVS:MountList:
  11.  
  12.     NULL:    Handler        = L:Null-Handler
  13.         Stacksize    = 500
  14.         Priority    = 5
  15.         GlobVec        = -1
  16.     #
  17.  
  18. You  _M_U_S_T_  install  the Null-Handler using the CLI command 'Mount
  19. NULL:' before starting KeyMacro or the KeyMacro handler won't budge.
  20.  
  21. ============================ BACKGROUND ==============================
  22. ======================================================================
  23. Some  time  ago  I  played around with a keymap editor to customize my
  24. keymap  settings.  But there was a feature I missed:  there wasn't any
  25. hot-key  support  (just  like  PopCLI  or  DMouse).  I also discovered
  26. another  disadvantage:   to change the keymap settings you had to load
  27. the  keymap  editor, edit the map, save it to disk and then install it
  28. via  SetMap  -  and even that didn't guarantee that the new keymap was
  29. accepted:   do  you  remember that SetMap does not load new keymaps if
  30. the  name matches a keymap already in memory?  Furthermore keymap keys
  31. may only generate string sequences of up to 32 characters.  With these
  32. topics in mind I decided to write my own keyboard macro handler.
  33.  
  34. ============================= FEATURES ===============================
  35. ======================================================================
  36. KeyMacro  provides  an  easy  way to manage keyboard macros (character
  37. sequences)  and  hot-key program execution.  You edit a script file in
  38. which  all  required key combinations are defined and call KeyMacro to
  39. update the macro list - that's all.  You can map up to eight functions
  40. to  each  key, including keys such as the cursor keys, the return key,
  41. etc.   The hot-key programs will use an AmigaDOS search path list when
  42. getting  executed.  Each macro key call gets processed asynchronously,
  43. i.e.   invoking  one  hot-key  command  after the other will start all
  44. commands in a row, nothing will be skipped.
  45.  
  46. =========================== INSTALLATION =============================
  47. ======================================================================
  48. Place  KeyMacro-Handler in L:, KeyMacro in C:  or SYS:, arp.library in
  49. LIBS:,   copy   your   KeyMacro.config  to  S:.   Type  "KeyMacro"  to
  50. install/update  macro  keys, "KeyMacro quit" to remove.  Note:  if the
  51. installation  fails  the  main  process  ("KeyMacro")  will wait for a
  52. handshake signal which may never arrive.  In this case pressing CTRL-C
  53. will  stop  the  main  process.   It will shut down and issue an error
  54. message.
  55.  
  56. =============================== USAGE ================================
  57. ======================================================================
  58. KeyMacro is controlled via a script file.  Here is a sample:
  59.  
  60.     ; KeyMacro v1.12 configuration file.
  61.     ; The semicolon indicates that this is a comment:
  62.  
  63.     ; Some keyboard macros.
  64.  
  65.     key ctrl+esc = "EndCLI > NIL:\n"
  66.     key lalt+0 = "CD DF0:\n"
  67.     key lalt+1 = "CD DF1:\n"
  68.  
  69.     ; A hot-key command definition
  70.  
  71.     command lalt+v = "C:vt100 +i s:vt100.init" window "VT100"
  72.  
  73. Each  definition  must  be  "key"  or "command".  "Key" means that the
  74. following  definition  will be a sequence of characters to be inserted
  75. into  the input stream.  "Command" means that the following definition
  76. will be the name and the arguments of a program to be executed.
  77.     The  macro  type  is  followed  by  the  key combination to be
  78. pressed to execute the macro definition.  This combination consists of
  79. the keyboard qualifier and the key.  An unlimited number of qualifiers
  80. is allowed.  KeyMacro knows the following qualifiers:
  81.  
  82.     NONE ..........    No qualifier (note: a qualifier MUST be given!)    
  83.     CTRL ..........    The control key
  84.     NUMPAD ........    The numeric pad
  85.     LSHIFT ........    The left shift key
  86.     RSHIFT ........    The right shift key
  87.     LALT ..........    The left alternate key
  88.     RALT ..........    The right alternate key
  89.     LAMIGA ........    The left Amiga key (Commodore key)
  90.     RAMIGA ........    The right Amiga key
  91.  
  92. A qualifier must be given or the macro parser will panic; if you don't
  93. need a qualifier simply enter NONE as the qualifier.
  94.     The  qualifier  is  followed  by  the  key to attach the macro
  95. expression  to.   This  can  be  any  key  on  the keyboard, including
  96. function keys, cursor keys, etc.  If there is no ASCII value available
  97. for the key, you can take a name from the following list:
  98.  
  99.     TAB ...........    The tabulator key
  100.     ESC ...........    The escape key
  101.     SPACE .........    The space key
  102.     RETURN ........    The return key
  103.     ENTER .........    The enter key (numeric pad)
  104.     DEL ...........    The delete key
  105.     BACKSPACE .....    The backspace key
  106.     HELP ..........    The help key
  107.  
  108.     LEFT ..........    The cursor-left key
  109.     RIGHT .........    The cursor-right key
  110.     UP ............    The cursor-up key
  111.     DOWN ..........    The cursor-down key
  112.  
  113.     F1 ............    The function key #1
  114.     F2 ............    The function key #2
  115.     F3 ............    The function key #3
  116.     F4 ............    The function key #4
  117.     F5 ............    The function key #5
  118.     F6 ............    The function key #6
  119.     F7 ............    The function key #7
  120.     F8 ............    The function key #8
  121.     F9 ............    The function key #9
  122.     F10 ...........    The function key #10
  123.  
  124. These  equivalents  can  be  used just like characters.  Note:  if you
  125. enter more than one single character as the command key only the first
  126. character will be taken (except for the key names listed above).
  127.     The key is followed by a '=' sign, this tells the macro parser
  128. to   remember   the  following  string  as  the  macro  string  to  be
  129. entered/executed.   This  string  must  be  enclosed  in quotes or the
  130. parser will take only the first word.  Inside this string sequences of
  131. two  characters can be used to generate key codes not supported by the
  132. ASCII keyboard.  These sequences are:
  133.  
  134.     \u ............    Cursor-up key
  135.     \d ............    Cursor-down key
  136.     \l ............    Cursor-left key
  137.     \r ............    Cursor-right key
  138.  
  139.     \n ............    The return key
  140.  
  141.     \h ............    The help key
  142.     \b ............    The backspace key
  143.     \e ............    The delete key (sorry, \d was already used)
  144.     \f1 - \f10 ....    The function keys
  145.     \" ............    A quote
  146.     \\ ............    The escape symbol ('\')
  147.  
  148. A  hot-key  command  definition can be followed by a "window" keyword.
  149. This  keyword  identifies  the next string (enclosed in quotes) as the
  150. typical window title of the command to be loaded.  Before this command
  151. is  executed  each open window is checked for this title.  If a window
  152. title matches the name it is brought to the front, no new command will
  153. be loaded.
  154.  
  155.                                   *
  156.  
  157.            KeyMacro has the following command-line options:
  158.  
  159. Startup .......    Followed  by  the  name  of  the file to be used as
  160.         configuration  file will keep KeyMacro from looking
  161.         for S:KeyMacro.config as the standard configuration
  162.         file.
  163.  
  164. Quit ..........    Removes KeyMacro from memory.
  165.  
  166. Delay .........    You  will  need  this  keyword  if  the  keypresses
  167.         KeyMacro  emits  do  not  produce sensible results,
  168.         i.e.   the  output  is  garbled  or  characters are
  169.         swallowed.   You  may specify the delay between the
  170.         single  keypresses.   The  rate  must  be  given in
  171.         microseconds, i.e.  a value of 1000000 will produce
  172.         a  delay  of  one second (you won't be needing this
  173.         much,  will  you?), 500000 will wait half a second.
  174.         For  technical  reasons the delay rate has to be >=
  175.         10000.
  176.  
  177. Priority.......    Input handler priority, default is 51 which inserts
  178.         the  input  handler  just  in  front of Intuition's
  179.         handler.   You  may  want  to  change this value to
  180.         avoid  conflicts  with  other  handlers  running at
  181.         priority  51.   Note that this keyword is active on
  182.         initial invocation only.
  183.  
  184. Info ..........    Gives a brief information on the program.
  185.  
  186. ============================== CREDITS ===============================
  187. ======================================================================
  188. Credits  go  to ARP Programmers for the most recent version of ARP, to
  189. Paul  Kienitz  for  his  FakeCLI  package, to Mark R.  Rinfret for the
  190. buffered Arp I/O routines, to Matt Dillon for DMouse, Jimm Mackraz for
  191. the  original  key  inversion routines, Eric Cotton & Carolyn Sheppner
  192. for their `International Keyboard Input' article and to Bill Hawes for
  193. his `cmap.asm' example keymap code.
  194.  
  195. ================== COPY FEE, AUTHORS REQUEST, ETC. ===================
  196. ======================================================================
  197. This  is the first time I release a program as shareware.  Consider it
  198. as  a  "test balloon" for coming projects.  A small contribution of at
  199. least $10 US or at least DM 15,- will insure your registration, giving
  200. you  the  opportunity  to  receive  updates, new programs from MXM and
  201. more.   Think about it, if you like this program and use it often this
  202. small  amount  of  money  will support the author and encourage him to
  203. start new projects.
  204.  
  205.        Send comments, bug reports, ideas and contributions to:
  206.  
  207.                           Olaf Barthel, MXM
  208.                           Brabeckstrasse 35
  209.                           D-3000 Hannover 71
  210.  
  211.                      Federal Republic of Germany
  212.  
  213. Permission  hereby  granted  to  re-distribute  KeyMacro  v1.12 in its
  214. entirety for non profit usage only.
  215.  
  216. ============ REVISION HISTORY (most recent change first) =============
  217. ======================================================================
  218. V1.12    This  time  it  works.  Really, it does!  There are new keymap
  219.     inversion routines in this release which even permit to create
  220.     accented characters such as à, è, î, ñ, etc.  The new code has
  221.     been  tested  with  any  keymap file available on disk and has
  222.     proven  reliable  and stable.  The code was ported to SAS/C, a
  223.     few  bugs  were  crushed  in the handler, most notable results
  224.     are:   the `builtin' macro key limit of 20 macros is gone, the
  225.     macro  list  now  consists  of  a  dynamically allocated list;
  226.     macros will no longer trap other macros (the popular qualifier
  227.     bug is gone); the input handler priority may be set on initial
  228.     program  invocation.  The pop-up-requestors have been changed,
  229.     they perform much faster now.
  230.  
  231. V1.11    Internal.
  232. V1.10    "
  233. V1.9    "
  234.  
  235. V1.8    The  keymap  inversion  routines  were  responsible  for funny
  236.     sideeffects,  such  as  characters  being swallowed instead of
  237.     being fed into the input stream.  It took me about three hours
  238.     to figure out what a `dead key-modifiable' keymap entry is and
  239.     another hour to program my own keymap reader.
  240.  
  241. V1.7    Added  the  delay  keyword  and  fixed a bug in KeyMacro which
  242.     caused a crash if KeyMacro-Handler could not be loaded.
  243.  
  244. V1.6    Thanks  to  user  persistance  KeyMacro was thoroughly revised
  245.     (yes, I mean what I say!).  Bert L.  Allen discovered problems
  246.     with the numeric key pad, Ralf Thanner suggested that I should
  247.     get rid of mxm.library, Martin Berndt and Benito Lombardi made
  248.     helpful  suggestions.   The  dreaded  mxm.library  was finally
  249.     removed,  saving about 20 KByte when there is no other program
  250.     to  access  the mxm.library routines.  The routine to simulate
  251.     the  key  events  will produce a key-down followed by a key-up
  252.     event.   Macros will no longer invoke other macros on the way.
  253.     InputEvents  created  by  KeyMacro-Handler  will  have a valid
  254.     timestamp.   Key  names are no longer abbreviated (i.e.  'f10'
  255.     !=  'f1').  The return key will finally work in cases where it
  256.     wouldn't work in revision 1.4.
  257.  
  258. V1.5    Small changes to library and code, recompiled  using  the  new
  259.     Aztec 'C' 5.0b compiler.
  260.  
  261. V1.4    Wow!   It  works!   The reasons for the constant failures were
  262.     located  in  1) mxm.library, 2) in the Arp wrapper for Lattice
  263.     'C',   3)   in   KeyMacro   itself   and   4)   of  course  in
  264.     KeyMacro-Handler.   Needless to say, mxm.library was fixed and
  265.     the code has once more changed the compiler - KeyMacro 1.4 now
  266.     compiles   under   Aztec   5.0.    Programs   started  by  the
  267.     executor-process will no longer block until the program exits.
  268.     This  is  now  probably  the only input.device example program
  269.     written  in  Aztec  'C'  which doesn't use ANY inline assembly
  270.     language code (#asm/#endasm).
  271.  
  272. V1.3    Well, I wouldn't shoot  my  grandma  to get it working, but it
  273.     really  starts  to  become  a  nuisance:  1.2 still wasn't the
  274.     success  I  had  expected.  I took a second look into RKM Exec
  275.     and  discovered  that  interrupt handlers be located in public
  276.     ram.   As  a  result  almost all static data declarations have
  277.     been replaced by memory allocations.
  278.  
  279. V1.2    I  guess  you know what happened:  it still didn't work right.
  280.     The  code  is  now  much  more compact and has been recompiled
  281.     using Lattice 'C' 5.04.
  282.  
  283. V1.1    KeyMacro  obviously  worked  on  only  one machine:  my Amiga.
  284.     This  is the first attempt to fix it.  I cleaned up the code I
  285.     didn't  think  to  be that much important which hopefully will
  286.     fix the problem.
  287.  
  288. V1.0    First  public  release;  seems  that  it  works (what did I do
  289.     wrong?).
  290.  
  291.                                   *
  292.  
  293.              Do only its possibilities make it an Amiga?
  294.  
  295.                         WHERE IS THE MAGIC ???
  296.